Format Date-time R←X(1200⌶)Y

Y is a numeric array of any shape, where every element contains a Dyalog Date Number that represents a date between 1 January 0001 and 31 December 9999 in the Proleptic Gregorian Calendar.

X is a character scalar or vector specifying a pattern with which the elements in Y should be formatted.

R is an array of the same shape as Y, whose elements are enclosed character vectors.

Formatting Pattern in X

The formatting pattern allows a time number to be converted to a highly user-configurable, plain text format. When a time number is formatted, elements in the result are copies of the format pattern with format sequences replaced by the elements they represent.

The format sequences are intended to be visually reminiscent of the generated text. They use alphabetic characters easily associated with the substitution (for example, D, M and Y for Day, Month and Year respectively) repeated one or more times to indicate format. As noted below, some sequences allow the first character to be replaced by a _, or the casing to be altered.

Format letter Length Meaning Variations Example
Year YY Without century YY 19
YYYY With century YYYY 2019
Month M 1 or 2 digit numeric M 3
MM 2 character numeric MM
_M
03
3
MMM Abbreviated name MMM
Mmm
mmm
_mm1
MAR
Mar
mar
Mar
MMMM Full name MMMM
Mmmm
mmmm
_mmm1
MARCH
March
march
March
Day of month D 1 or 2 digit numeric D 4
DD 2 character numeric DD
_D
04
4
hours h 1 or 2 digit numeric h 8
hh 2 character numeric hh
_h
08
8
minutes m 1 or 2 digit numeric m 5
mm 2 character numeric mm
_m
05
5
seconds s 1 or 2 digit numeric s 0
ss 2 character numeric ss
_s
00
0
fractional seconds f 1 digit precision f 5
ff 2 digit precision ff 55
fff 3 digit precision fff 555
ffff 4 digit precision ffff 5555
fffff 5 digit precision fffff 55555
ffffff 6 digit precision ffffff 555555
day of week d Numeric (1-7) d 1
ddd Abbreviated name DDD
Ddd
ddd
_dd1
MON
Mon
mon
Mon
dddd Full name DDDD
Dddd
dddd
_ddd1
MONDAY
Monday
monday
Monday
ISO week number w 1 or 2 digit numeric w 10
ww 2 character numeric ww
_w
10
10
year of ISO
Week
number2
WW Without century WW 19
WWWW With century WWWW 2019
day of year y 1 to 3 digit numeric y 63
yy 3 character numeric yy
_y
063
63
Ordinal indicator3
for day of month
O Short O
o
T
t
OO Full OO
Oo
oo
TH
Th
th
hours in twelve
hour clock
t 1 or 2 digit numeric t 8
tt 2 character numeric tt
_t
08
AM/PM Indicator P Short P
p
A
a
PP Full PP
pp
AM
am

The upper and lower case letters, underscore _, dollar $ and percent % are all reserved for introducing format sequences, even though not all currently have meaning. The remaining, non-reserved, characters are copied to the result unchanged, thus the format string hh:mm represents the hour of the day and minute of the hour with a colon between (for example, 12:00). All characters or sequences of characters may be delimited by " or ' at any point in the format string to prevent them being interpreted as a part of a format sequence, and, within these delimiters, two adjacent delimiter characters produce a single delimiter.

Note: The characters AaaaBbbb consist of two adjacent format sequences because there is a sequence of As followed by a sequence of Bs. The characters AaaaAaaa consist of one format sequence because it only contains As. It can be separated into two format sequences by inserting an empty " or ' - delimited string, for example, Aaaa""Aaaa.

Language

Unless overridden, English is used for text substitutions. Different languages may be selected using the Language variant option and/or the use of language specifiers within the format pattern. In either case, the language is specified as either a two letter ISO 639-1 language code in lower case (for example, en) or as a five character language with an additional underscore and two character region in upper case (for example, en_GB). Within the format pattern, __xx__ (where xx is the two or five character specifier) will switch the language of the subsequent generated text. Dictionaries for the following languages are built in:

ISO 639-1 Language
da Danish
de German
el Greek
en English
es Spanish
fi Finnish
fr French
it Italian
ja Japanese
nb Norwegian Bokmål
nl Dutch
nn Norwegian Nynorsk
pl Polish
pt Portuguese
ru Russian
sv Swedish
zh Chinese

Predefined patterns

Any pattern can contain (in part or in whole) a named predefined pattern, which allows common date and time formats to be specified in abbreviated form. Predefined patterns may be specified on a per-language basis, allowing patterns to be tailored for the selected language.

Predefined patterns are included in a pattern using % delimiters. For example, %ISO% includes the named predefined pattern ISO.

The following global predefined pattern is built in:

Name Substitutes as
ISO1 YYYY-MM-DD"T"hh:mm:ss
  1. An ISO 8601 extended format calendar date and time with no time zone designator.

This list may be expanded in future.

Additional predefined patterns may be defined using the Dictionary variant option. Predefined patterns must not contain references to other predefined patterns.

Variant Options

The Language variant option specifies the language used for formatting datetimes and defaults to 'en' (English). The option value is a two or five character name (for example, 'en' or 'en_GB'). The setting may be explicitly overridden in the format pattern.

The Dictionary variant option specifies a namespace which contains additional or replacement names for the months etc. and/or predefined patterns, for languages and language regions.

At the top level there may be zero or more sub-namespaces with two or five character names, according to the rules for language and language regions. Within each of these, month names etc. are defined as follows:

Named item Description
MonthNames A twelve-element vector of character vectors containing the full names corresponding to January to December, respectively.
ShortMonthNames A twelve-element vector of character vectors containing the short names corresponding to Jan to Dec, respectively.
WeekdayNames A seven-element vector of character vectors containing the full names corresponding to Monday to Sunday, respectively.
ShortWeekdayNames A seven-element vector of character vectors containing the full names corresponding to Mon to Sun, respectively.
MorningAfternoon A two-element vector of character vectors containing the names corresponding to AM and PM, respectively.
Ordinals A character vector containing the one ordinal used for all numbers in the range 1 to 31, or a thirty one-element vector of character vectors containing the ordinals for 1 to 31, respectively.

Also at the top level of the dictionary namespace there may be a sub-namespace named Patterns and within this further sub-namespaces named Global and/or two or five character language names, containing definitions of predefined patterns. Predefined patterns are defined in the same way as the formatting pattern except that they may not contain references to other predefined patterns.

If the namespace contains a definition which is supplied built into the interpreter, it replaces the built-in one.

If a dictionary is incomplete (for example, if it is missing one of the expected named items, or one of the named items contains too few elements) an error is signalled only if the missing content would actually be needed.

Example dictionary

The following creates a dictionary defined by the namespace dict using JSON text. See the formatting examples below for uses of this dictionary.

      dict_json
{
  "Patterns": {
    "Global": {
      "ISOweek": "YYYY-'W'ww",
      "DateCompact": "D-MMM-YYYY",
      "DateVerbose": "'the date is' DD _mm YYYY"
    },
    "fr": {
      "DateVerbose": "'la date est le' DD mmm YYYY"
    },
    "en_US": {
      "DateVerbose": "'the date is' Mmm DD, YYYY"
    }
  },
  "en_US": {
    "ShortMonthNames": [
      "Jan.", "Feb.", "Mar.", "Apr.", "May", "June",
      "July", "Aug.", "Sept.", "Oct.", "Nov.", "Dec."
    ]
  },
  "cy": {
    "MonthNames": [
      "Ionawr", "Chwefror", "Mawrth", "Ebrill", "Mai", "Mehefin",
      "Gorffennaf", "Awst", "Medi", "Hydref", "Tachwedd", "Rhagfyr"
    ],
    "ShortMonthNames": [
      "Ion", "Chw", "Maw", "Ebr", "Mai", "Meh",
      "Gor", "Awst", "Medi", "Hyd", "Tach", "Rhag"
    ],
    "WeekdayNames": [
      "Dydd Sul", "Dydd Llun", "Dydd Mawrth", "Dydd Mercher",
      "Dydd Iau", "Dydd Gwener", "Dydd Sadwrn"
    ],
    "ShortWeekdayNames": [
      "Sul", "Llun", "Maw", "Mer", "Iau", "Gwen", "Sad"
    ],
    "MorningAfternoon": [
      "yb", "yh"
    ],
    "Ordinals": [
      "af", "il", "ydd", "ydd", "ed", "ed", "fed", "fed", "fed",
      "fed", "eg", "fed", "eg", "eg", "fed", "eg", "eg", "fed",
      "eg", "fed", "ain", "ain", "ain", "ain", "ain", "ain",
      "ain", "ain", "ain", "ain", "ain"
    ]
  }
}
      dict←⎕JSON dict_json

Note the following:

In the following examples:

      tn←1 ⎕DT ⊂2019 2 13 10 16 56
      tn
43508.42843

English

      'Dddd, DDoo Mmmm YYYY; hh:mm:ss' (1200⌶) tn
 Wednesday, 13th February 2019; 10:16:56

      '__en__Dddd, DDoo Mmmm YYYY; hh:mm:ss' (1200⌶) tn
 Wednesday, 13th February 2019; 10:16:56

      '"ISO date": %ISO%' (1200⌶) tn
 ISO date: 2019-02-13T10:16:56

      '%DateVerbose%'(1200⌶⍠'Dictionary'dict) tn
 the date is 13 Feb 2019

English (US)

     fmt←'%DateVerbose%'
     fmt (1200⌶⍠('Dictionary'dict)('Language' 'en_US'))tn
 the date is Feb. 13, 2019 

Danish

      '__da__Dddd, DDoo mmmm YYYY; hh:mm:ss' (1200⌶) tn
 Onsdag, 13. februar 2019; 10:16:56

      fmt←'Dddd, DDoo mmmm YYYY; hh:mm:ss'
      fmt(1200⌶⍠'Language' 'da') tn
 Onsdag, 13. februar 2019; 10:16:56 

Welsh (using the dictionary defined above)

      fmt←'__cy__Dddd, DDoo mmmm YYYY; hh:mm:ss' 
      fmt (1200⌶⍠'Dictionary' dict) tn
 Dydd Mercher, 13eg chwefror 2019; 10:16:56 


      '__cy__%DateVerbose%' (1200⌶⍠'Dictionary' dict) tn
 the date is 13 Chw 2019